Java Bridge

Java Bridgehttp://bill.welliver.org//space/pike/Java BridgeThis is a very slightly prettied up version of the presentation I gave at the 2003 Pike Conference in Paderborn. It's basically an overview of what's going on in the Java module. Contact me if you're interested in having a copy of the original text document (it might be easier to read in certain situations). JNI Specification Defines methods for embedding a Java VM within an application. Access to Java objects from the application embedding the Java VM. Provides access to functions within the application to the embedded Java VM (native methods) <img height="9" width="8" src="/static/images/Icon-Extlink.png" alt="[external]"/><a href="http://java.sun.com/products/jdk/1.2/docs/guide/jni/">http://java.sun.com/products/jdk/1.2/docs/guide/jni/</a> The Pike Implementation Located in the Java module. Supported on systems containing a Java v1.2+ installation. Known to work with both the Sun JDK and IBM JDK Using the Java bridge. <ul class="minus"> <li>The Hard Way</li> </ul> Java.machine starts up a Java VM and leaves the rest to you Pros: Less overhead (speed and memory-wise), more direct control of your interaction with the Java VM Cons: Tedious, time-consuming to set up, not very Pikeish <ul class="minus"> <li>The Easy Way</li> </ul> Java.pkg will load a java package and connect all of the functions and fields so that they (nominally) act like other pike objects. Pros: much easier to access Java functionality Cons: slower, due to object setup and wrappings, less control over how things are set up and connected, doesn't completely hide you from Javaness Java VM create(string|void arg) In theory, you should be able to start a vm with arg as the classpath. In reality, this doesn't work so well. int get_version() Returns the version code of the JVM running. object find_class(string c) Finds the class c, using "/" instead of "." as the class separator. Returns the class or zero if the class was not found, in addition to throwing an exception. object define_class(object cl, string bc) prepare a java class object from a string of java bytecode cl is a class loader object Note: doesn't seem to work properly. int exception_check() checks to see if an exception is being thrown. object exception_occurred() returns the exception object, if one has been thrown. void exception_describe() prints an exception description and backtrace to stderr void exception_clear() clears any exceptions void fatal(string arg) Raises a fatal error; the VM quits, taking Pike with it. object new_boolean_array(int) object new_byte_array(int) object new_char_array(int) object new_short_array(int) object new_int_array(int) object new_long_array(int) object new_float_array(int) object new_double_array(int) Java Object: mixed cast(string) casts the object to another datatype. Currently, only casting to string is supported. int `==(mixed) are two objects the same? int _ _hash() calls the hashCode method of the object int is_instance_of(object arg) determines whether the object is an instance of arg object monitor_enter() returns a Java.monitor object object get_object_class() returns the class of an object Java Class: inherits Java Object object register_natives(array(array(string|function)) arg) registers one or more native methods for a class. the class must have the functions defined as "native" arg[n][0] is a string containing the method name to define arg[n][1] is a string describing the method signature to define for the given method arg[n][2] is a function to be called when the method is called from Java object|0 super_class() Returns the superclass of the object, zero if the object is a java.lang.Object. int is_assignable_from(object c) Returns TRUE if: The argument refers to the same Java class as the object itself. The argument class is a subclass of the object. The argument has the object as one of its interfaces. void throw_new(string arg) Throws an exception or error (if the object is a child one of these classes), with the optional description of arg Produces an exception that may be caught or checked using one of the exception checks. object alloc() allocates a new Java object without invoking its constructors. returns the new object. object new_array(int, object|void) object get_method(string name, string sig) gets method name with signature sig from the class. returns the method or zero if the name and signature do not match any in the class. object get_static_method(string, string) gets a static method name with signature sig from the class. returns the method or zero if the name and signature do not match any in the class. object get_field(string name, string sig) gets a field name with a type of sig from the class. returns the field object or zero if the name and signature do not match any in the class. object get_static_field(string, string) gets a static field name with a type of sig from the class. returns the field object or zero if the name and signature do not match any in the class. Java Throwable inherits Java Object void throw() Java Array inherits Java Object _sizeof() `[] `[]= _indices _values Java Static Method mixed `(mixed… args) calls the method with arguments args. Java Method mixed `(object obj, mixed… args) calls the method as defined in object obj, with arguments args. mixed call_nonvirtual(object obj, mixed … args) calls the method as defined in the class the method is derived from, with arguments args. Java Field & Static Fields mixed set(mixed val) sets the value of a field to val. mixed get() returns the value of a field Objects used internally by the module: Java Monitor Java Natives Java Attachment The Java Package interface The Java.package module provides convenient access to an entire Java Class package, performing a number of useful tricks along the way. The module will look for a package, load the class, set up access to all of its fields and methods, making it look very much like a Pike object. Usage: <div class="code"><pre><pre> > object i=Java.pkg&#91;"java/lang/Integer"]; > i(52); > indices(i); Result: ({ /* 14 elements */ "wait", "getClass", "doubleValue", "longValue", "toString", "equals", "compareTo", "hashCode", "floatValue", "shortValue", "notifyAll", "notify", "intValue", "byteValue" }) > (string)i->toString(); Result: "52" </pre></pre></div> What the Java.package module does not do: <ul class="minus"> <li>convert Pike datatypes into Java datatype objects</li> <li>convert Java datatype objects into Pike datatypes</li> <li>attempt to guess what function signature you wish to use if it's at all ambiguous.</li> <li>completely mask the Java bridge and its Javaness from the Pike user, though it comes quite a bit of the way.</li> </ul>Using Java.package The package interface to Java is straightforward in use. The Java module creates an instance of the package interface called "pkg" on startup. The package interface exposes its functionality by overloading the indexing operator. To access a java class, simply ask Java.pkg for it: > object myclass = Java.pkg["org/welliver/conference/myclass"]; Result: Java.jclass() An error will be thrown if the requested class cannot be found. Java.jclass represents a Java Class in Pike. `(mixed … args) calls the constructor that most closely matches args. will not attempt to choose if more than one method signature matches. `[n] returns the value of a static field n or a static method object n `->n returns the value if `[n] unless n[0..0]=="_", in which case it returns: _fields: returns a mapping of the field objects in the class _static_fields: returns a mapping of the static field objects in the class _methods: returns a mapping of the method objects in the class _static_methods: returns a mapping of the method objects in the class _wrap_result: returns the wrap result function, used to turn a Java.object into a Java.jobject _method: returns the method selector function _constructor: returns the constructor selector function _alloc: returns the alloc function of the base Java.object _register_natives: returns the register_natives function of the base Java.object Java.jmethod _method(string n, string sig) returns the java method that matches name n and type signature sig. Java.jconstructor _constructor(string sig) returns the java constructor for this class that matches type signature sig. Java.jconstructor represents a Java constructor in Pike. Java.jobject `(mixed … args) calls the constructor of the class with arguments args. Java.jmethod represents a Java method in Pike. Java.jobject `(mixed … args) calls the function with arguments args. Java.method for_protos(string sig) returns the Java method matching the type signature sig. Used internally. Java.jmethod for_object(object obj) returns a jmethod object for the object obj. Used internally. Java.jobject represents a Java object in Pike. cast(mixed type) calls the cast function for the underlying Java object. Note that this only works with the argument of "string". `[n] returns the field or method n from the class. `->n returns the value of `[n] unless n[0..0]=="_", in which case it returns: _method: returns the method selector function. _obj: returns the low level Java.object object. _monitor_enter: returns the Java.monitor object associated with this class. _values() returns the values of the object, matching its indices. _indices() returns the indices of the object, ie field and method names. Java.jmethod _method(string n, string sig) returns the java method that matches name n and type signature sig. Java.jarray represents a Java array in Pike. cast(mixed … arg) `[n] returns the nth element of the array: length: returns the number of elements in the array _monitor_enter: returns the monitor object associated with this instance _obj: returns the low level object for this array `[n]=x attempts to set the value of the nth element to x. `->n returns the following: length: returns the number of elements in the array _monitor_enter: returns the monitor object associated with this instance _obj: returns the low level object for this array _sizeof() _indices() _values() overloads to make an array object seem more Pikeish. Java Convenience Functions The following functions will convert a Pike datatype to a relatively common Java equivalent. Their behavior is general, and any value may be provided to them, as long as they are the specified type. Any exceptions are noted below. Java.JInteger(int i) Java.JString(string s) Java.JFloat(float f) Java.JBoolean(int b) any value other than 0 is true, 0 is false. Java.JArray(array(mixed) a) can encode an array of any type, however all of the elements must be the same type. that is, you may not mix strings and floats as values in the array Java.JHashMap(mapping m) Java.JVector(multiset x) Fins 0.9.7http://blogs.law.harvard.edu/tech/rss